home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / ctgsna.z / ctgsna
Encoding:
Text File  |  2002-10-03  |  10.9 KB  |  331 lines
  1.  
  2.  
  3.  
  4. CCCCTTTTGGGGSSSSNNNNAAAA((((3333SSSS))))                                                          CCCCTTTTGGGGSSSSNNNNAAAA((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      CTGSNA - estimate reciprocal condition numbers for specified eigenvalues
  10.      and/or eigenvectors of a matrix pair (A, B)
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE CTGSNA( JOB, HOWMNY, SELECT, N, A, LDA, B, LDB, VL, LDVL, VR,
  14.                         LDVR, S, DIF, MM, M, WORK, LWORK, IWORK, INFO )
  15.  
  16.          CHARACTER      HOWMNY, JOB
  17.  
  18.          INTEGER        INFO, LDA, LDB, LDVL, LDVR, LWORK, M, MM, N
  19.  
  20.          LOGICAL        SELECT( * )
  21.  
  22.          INTEGER        IWORK( * )
  23.  
  24.          REAL           DIF( * ), S( * )
  25.  
  26.          COMPLEX        A( LDA, * ), B( LDB, * ), VL( LDVL, * ), VR( LDVR, *
  27.                         ), WORK( * )
  28.  
  29. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  30.      These routines are part of the SCSL Scientific Library and can be loaded
  31.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  32.      directs the linker to use the multi-processor version of the library.
  33.  
  34.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  35.      4 bytes (32 bits). Another version of SCSL is available in which integers
  36.      are 8 bytes (64 bits).  This version allows the user access to larger
  37.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  38.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  39.      only one of the two versions; 4-byte integer and 8-byte integer library
  40.      calls cannot be mixed.
  41.  
  42. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  43.      CTGSNA estimates reciprocal condition numbers for specified eigenvalues
  44.      and/or eigenvectors of a matrix pair (A, B). (A, B) must be in
  45.      generalized Schur canonical form, that is, A and B are both upper
  46.      triangular.
  47.  
  48.  
  49. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  50.      JOB     (input) CHARACTER*1
  51.              Specifies whether condition numbers are required for eigenvalues
  52.              (S) or eigenvectors (DIF):
  53.              = 'E': for eigenvalues only (S);
  54.              = 'V': for eigenvectors only (DIF);
  55.              = 'B': for both eigenvalues and eigenvectors (S and DIF).
  56.  
  57.      HOWMNY  (input) CHARACTER*1
  58.              = 'A': compute condition numbers for all eigenpairs;
  59.              = 'S': compute condition numbers for selected eigenpairs
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CCCCTTTTGGGGSSSSNNNNAAAA((((3333SSSS))))                                                          CCCCTTTTGGGGSSSSNNNNAAAA((((3333SSSS))))
  71.  
  72.  
  73.  
  74.              specified by the array SELECT.
  75.  
  76.      SELECT  (input) LOGICAL array, dimension (N)
  77.              If HOWMNY = 'S', SELECT specifies the eigenpairs for which
  78.              condition numbers are required. To select condition numbers for
  79.              the corresponding j-th eigenvalue and/or eigenvector, SELECT(j)
  80.              must be set to .TRUE..  If HOWMNY = 'A', SELECT is not
  81.              referenced.
  82.  
  83.      N       (input) INTEGER
  84.              The order of the square matrix pair (A, B). N >= 0.
  85.  
  86.      A       (input) COMPLEX array, dimension (LDA,N)
  87.              The upper triangular matrix A in the pair (A,B).
  88.  
  89.      LDA     (input) INTEGER
  90.              The leading dimension of the array A. LDA >= max(1,N).
  91.  
  92.      B       (input) COMPLEX array, dimension (LDB,N)
  93.              The upper triangular matrix B in the pair (A, B).
  94.  
  95.      LDB     (input) INTEGER
  96.              The leading dimension of the array B. LDB >= max(1,N).
  97.  
  98.      VL      (input) COMPLEX array, dimension (LDVL,M)
  99.              IF JOB = 'E' or 'B', VL must contain left eigenvectors of (A, B),
  100.              corresponding to the eigenpairs specified by HOWMNY and SELECT.
  101.              The eigenvectors must be stored in consecutive columns of VL, as
  102.              returned by CTGEVC.  If JOB = 'V', VL is not referenced.
  103.  
  104.      LDVL    (input) INTEGER
  105.              The leading dimension of the array VL. LDVL >= 1; and If JOB =
  106.              'E' or 'B', LDVL >= N.
  107.  
  108.      VR      (input) COMPLEX array, dimension (LDVR,M)
  109.              IF JOB = 'E' or 'B', VR must contain right eigenvectors of (A,
  110.              B), corresponding to the eigenpairs specified by HOWMNY and
  111.              SELECT.  The eigenvectors must be stored in consecutive columns
  112.              of VR, as returned by CTGEVC.  If JOB = 'V', VR is not
  113.              referenced.
  114.  
  115.      LDVR    (input) INTEGER
  116.              The leading dimension of the array VR. LDVR >= 1; If JOB = 'E' or
  117.              'B', LDVR >= N.
  118.  
  119.      S       (output) REAL array, dimension (MM)
  120.              If JOB = 'E' or 'B', the reciprocal condition numbers of the
  121.              selected eigenvalues, stored in consecutive elements of the
  122.              array.  If JOB = 'V', S is not referenced.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CCCCTTTTGGGGSSSSNNNNAAAA((((3333SSSS))))                                                          CCCCTTTTGGGGSSSSNNNNAAAA((((3333SSSS))))
  137.  
  138.  
  139.  
  140.      DIF     (output) REAL array, dimension (MM)
  141.              If JOB = 'V' or 'B', the estimated reciprocal condition numbers
  142.              of the selected eigenvectors, stored in consecutive elements of
  143.              the array.  If the eigenvalues cannot be reordered to compute
  144.              DIF(j), DIF(j) is set to 0; this can only occur when the true
  145.              value would be very small anyway.  For each eigenvalue/vector
  146.              specified by SELECT, DIF stores a Frobenius norm-based estimate
  147.              of Difl.  If JOB = 'E', DIF is not referenced.
  148.  
  149.      MM      (input) INTEGER
  150.              The number of elements in the arrays S and DIF. MM >= M.
  151.  
  152.      M       (output) INTEGER
  153.              The number of elements of the arrays S and DIF used to store the
  154.              specified condition numbers; for each selected eigenvalue one
  155.              element is used. If HOWMNY = 'A', M is set to N.
  156.  
  157.      WORK    (workspace/output) COMPLEX array, dimension (LWORK)
  158.              If JOB = 'E', WORK is not referenced.  Otherwise, on exit, if
  159.              INFO = 0, WORK(1) returns the optimal LWORK.
  160.  
  161.      LWORK  (input) INTEGER
  162.             The dimension of the array WORK. LWORK >= 1.  If JOB = 'V' or 'B',
  163.             LWORK >= 2*N*N.
  164.  
  165.      IWORK   (workspace) INTEGER array, dimension (N+2)
  166.              If JOB = 'E', IWORK is not referenced.
  167.  
  168.      INFO    (output) INTEGER
  169.              = 0: Successful exit
  170.              < 0: If INFO = -i, the i-th argument had an illegal value
  171.  
  172. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  173.      The reciprocal of the condition number of the i-th generalized eigenvalue
  174.      w = (a, b) is defined as
  175.  
  176.              S(I) = (|v'Au|**2 + |v'Bu|**2)**(1/2) / (norm(u)*norm(v))
  177.  
  178.      where u and v are the right and left eigenvectors of (A, B) corresponding
  179.      to w; |z| denotes the absolute value of the complex number, and norm(u)
  180.      denotes the 2-norm of the vector u. The pair (a, b) corresponds to an
  181.      eigenvalue w = a/b (= v'Au/v'Bu) of the matrix pair (A, B). If both a and
  182.      b equal zero, then (A,B) is singular and S(I) = -1 is returned.
  183.  
  184.      An approximate error bound on the chordal distance between the i-th
  185.      computed generalized eigenvalue w and the corresponding exact eigenvalue
  186.      lambda is
  187.  
  188.              chord(w, lambda) <=   EPS * norm(A, B) / S(I),
  189.  
  190.      where EPS is the machine precision.
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. CCCCTTTTGGGGSSSSNNNNAAAA((((3333SSSS))))                                                          CCCCTTTTGGGGSSSSNNNNAAAA((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      The reciprocal of the condition number of the right eigenvector u and
  207.      left eigenvector v corresponding to the generalized eigenvalue w is
  208.      defined as follows. Suppose
  209.  
  210.                       (A, B) = ( a   *  ) ( b  *  )  1
  211.                                ( 0  A22 ),( 0 B22 )  n-1
  212.                                  1  n-1     1 n-1
  213.  
  214.      Then the reciprocal condition number DIF(I) is
  215.  
  216.              Difl[(a, b), (A22, B22)]  = sigma-min( Zl )
  217.  
  218.      where sigma-min(Zl) denotes the smallest singular value of
  219.  
  220.             Zl = [ kron(a, In-1) -kron(1, A22) ]
  221.                  [ kron(b, In-1) -kron(1, B22) ].
  222.  
  223.      Here In-1 is the identity matrix of size n-1 and X' is the conjugate
  224.      transpose of X. kron(X, Y) is the Kronecker product between the matrices
  225.      X and Y.
  226.  
  227.      We approximate the smallest singular value of Zl with an upper bound.
  228.      This is done by CLATDF.
  229.  
  230.      An approximate error bound for a computed eigenvector VL(i) or VR(i) is
  231.      given by
  232.  
  233.                          EPS * norm(A, B) / DIF(i).
  234.  
  235.      See ref. [2-3] for more details and further references.
  236.  
  237.      Based on contributions by
  238.         Bo Kagstrom and Peter Poromaa, Department of Computing Science,
  239.         Umea University, S-901 87 Umea, Sweden.
  240.  
  241.      References
  242.      ==========
  243.  
  244.      [1] B. Kagstrom; A Direct Method for Reordering Eigenvalues in the
  245.          Generalized Real Schur Form of a Regular Matrix Pair (A, B), in
  246.          M.S. Moonen et al (eds), Linear Algebra for Large Scale and
  247.          Real-Time Applications, Kluwer Academic Publ. 1993, pp 195-218.
  248.  
  249.      [2] B. Kagstrom and P. Poromaa; Computing Eigenspaces with Specified
  250.          Eigenvalues of a Regular Matrix Pair (A, B) and Condition
  251.          Estimation: Theory, Algorithms and Software, Report
  252.          UMINF - 94.04, Department of Computing Science, Umea University,
  253.          S-901 87 Umea, Sweden, 1994. Also as LAPACK Working Note 87.
  254.          To appear in Numerical Algorithms, 1996.
  255.  
  256.      [3] B. Kagstrom and P. Poromaa, LAPACK-Style Algorithms and Software
  257.          for Solving the Generalized Sylvester Equation and Estimating the
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. CCCCTTTTGGGGSSSSNNNNAAAA((((3333SSSS))))                                                          CCCCTTTTGGGGSSSSNNNNAAAA((((3333SSSS))))
  269.  
  270.  
  271.  
  272.          Separation between Regular Matrix Pairs, Report UMINF - 93.23,
  273.          Department of Computing Science, Umea University, S-901 87 Umea,
  274.          Sweden, December 1993, Revised April 1994, Also as LAPACK Working
  275.          Note 75.
  276.          To appear in ACM Trans. on Math. Software, Vol 22, No 1, 1996.
  277.  
  278.  
  279. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  280.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  281.  
  282.      This man page is available only online.
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.